﻿<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Message</title>
<meta http-equiv="Content-Type" Content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../../styles/styles.css">
<script language="javascript" src='../links.js' type="text/javascript"></script>
</head>
<body>

<h1>Message</h1>
<div class=navbar>
<a href="../index.html">главная</a> |
<a href="index.html">сервисные функции</a> |
<a href="../basicapi/index.html">Basic API</a>
</div>

<div class=shortdescr>
Функция <code>Message</code> показывает сообщение.
</div>

<pre class=syntax>
intptr_t WINAPI Message(
  const GUID *PluginId,
  const GUID *Id,
  FARMESSAGEFLAGS Flags,
  const wchar_t *HelpTopic,
  const wchar_t * const *Items,
  size_t ItemsNumber,
  intptr_t ButtonsNumber
);
</pre>

<h3>Параметры</h3>
<div class=descr>
  <div class=dfn>PluginId</div>
    <div class=dfndescr>Указатель на GUID плагина (для вашего плагина, GUID должен быть таким же, что и в поле <code>GlobalInfo.Guid</code> функции <a href="../exported_functions/getglobalinfow.html">GetGlobalInfoW</a>).</div>
  <div class=dfn>Id</div>
    <div class=dfndescr>Указатель на GUID текущего сообщения. GUID должен быть уникальным.</div>
  <div class=dfn>Flags</div>
    <div class=dfndescr>Может быть комбинацией следующих значений (тип <a name="FARMESSAGEFLAGS">FARMESSAGEFLAGS</a>):
    <table class="cont">
    <tr class="cont"><th class="cont" width="40%">Флаг</th><th class="cont" width="60%">Описание</th></tr>
    <tr class="cont"><td class="cont" width="40%"><a name="FMSG_WARNING">FMSG_WARNING</a></td>
    <td class="cont" width="60%">Используются цвета &quot;Предупреждения&quot; (обычно белые буквы на красном фоне).</td></tr>
    <tr class="cont"><td class="cont" width="40%"><a name="FMSG_ERRORTYPE">FMSG_ERRORTYPE</a></td>
    <td class="cont" width="60%">Если тип ошибки, возвращаемый функцией <code>GetLastError</code>, <a href="../defs/winerror.html">известен Far Manager'у</a> или Windows,
    то описание ошибки будет выведено после строк, переданных плагином.</td></tr>
    <tr class="cont"><td class="cont" width="40%"><a name="FMSG_KEEPBACKGROUND">FMSG_KEEPBACKGROUND</a></td>
    <td class="cont" width="60%">Не перерисовывать фон сообщения.</td></tr>
    <tr class="cont"><td class="cont" width="40%"><a name="FMSG_LEFTALIGN">FMSG_LEFTALIGN</a></td>
    <td class="cont" width="60%">Использовать для строк сообщения выравнивание влево (по умолчанию строки выводятся по центру).</td></tr>
    <tr class="cont"><td class="cont" width="40%"><a name="FMSG_ALLINONE">FMSG_ALLINONE</a></td>
    <td class="cont" width="60%">В этом случае аргумент <code>Items</code> не является массивом указателей на строки - <dfn class=alert3>это УКАЗАТЕЛЬ на одну
    строку</dfn>, в которой разделителем выводимых строк является символ <code>'\n'</code>.
    <p>Минимальное количество строк - 2 - заголовок и одна строка сообщения.
    <p>При указании флага <code>FMSG_ALLINONE</code> аргумент <code>ItemsNumber</code> игнорируется и количество выводимых строк вычисляется автоматически (с учётом флагов-кнопок <code>FMSG_MB_*</code>).
    <p>Для подавления вывода заголовка при использовании флага <code>FMSG_ALLINONE</code> начните строку с символа <code>'\n'</code>.</td></tr>
    <tr class="cont"><td class="cont" width="40%"><a name="FMSG_MB_OK">FMSG_MB_OK</a></td>
    <td class="cont" width="60%">Дополнительно выводится кнопка &lt;Ok&gt;</td></tr>
    <tr class="cont"><td class="cont" width="40%"><a name="FMSG_MB_OKCANCEL">FMSG_MB_OKCANCEL</a></td>
    <td class="cont" width="60%">Дополнительно выводятся кнопки &lt;Ok&gt; и &lt;Cancel&gt;</td></tr>
    <tr class="cont"><td class="cont" width="40%"><a name="FMSG_MB_ABORTRETRYIGNORE">FMSG_MB_ABORTRETRYIGNORE</a></td>
    <td class="cont" width="60%">Дополнительно выводятся кнопки &lt;Abort&gt;, &lt;Retry&gt; и &lt;Ignore&gt;</td></tr>
    <tr class="cont"><td class="cont" width="40%"><a name="FMSG_MB_YESNO">FMSG_MB_YESNO</a></td>
    <td class="cont" width="60%">Дополнительно выводятся кнопки &lt;Yes&gt; и &lt;No&gt;</td></tr>
    <tr class="cont"><td class="cont" width="40%"><a name="FMSG_MB_YESNOCANCEL">FMSG_MB_YESNOCANCEL</a></td>
    <td class="cont" width="60%">Дополнительно выводятся кнопки &lt;Yes&gt;, &lt;No&gt; и &lt;Cancel&gt;</td></tr>
    <tr class="cont"><td class="cont" width="40%"><a name="FMSG_MB_RETRYCANCEL">FMSG_MB_RETRYCANCEL</a></td>
    <td class="cont" width="60%">Дополнительно выводятся кнопки &lt;Retry&gt; и &lt;Cancel&gt;</td></tr>
    <tr class="cont"><td class="cont" width="40%"><a name="FMSG_NONE">FMSG_NONE</a></td>
    <td class="cont" width="60%">Нулевой флаг</td></tr>
    </table>
    </div>
  <div class=dfn>HelpTopic</div>
    <div class=dfndescr><a href="../language/helptopic.html">Тема подсказки</a> в файле помощи связанная с сообщением. Установите это значение в <code>NULL</code> если подсказка не требуется.</div>
  <div class=dfn>Items</div>
    <div class=dfndescr>Адрес массива с указателями на Unicode строки. Первая строка - заголовок сообщения, последние <code>ButtonsNumber</code> строк - кнопки, все остальные строки принадлежат телу сообщения.<br>
    Для отрисовки одинарной разделительной линии начните строку с символа с кодом 1 (L"\1").<br>
    Для отрисовки двойной разделительной линии начните строку с символа с кодом 2 (L"\2").<br>
    Смотрите также описание флага <a href="#FMSG_ALLINONE">FMSG_ALLINONE</a>.</div>
  <div class=dfn>ItemsNumber</div>
    <div class=dfndescr>Количество указателей в массиве <code>Items</code>. Минимальное значение - 2 строки.</div>
  <div class=dfn>ButtonsNumber</div>
    <div class=dfndescr>Количество заключительных строк, которые будут использоваться в качестве кнопок. При указании флагов <code>FMSG_MB_*</code>  параметр <code>ButtonsNumber</code> игнорируется.</div>
</div>

<h3>Возвращаемое значение</h3>
<div class=descr>
Функция возвращает <code>-1</code>, если пользователь отменил сообщение (или системе не удалось выделить достаточно памяти для внутренних буферов),
или выбранный номер кнопки (для первой кнопки - <code>0</code>, для второй - <code>1</code> и так далее).
</div>

<h3>Замечания</h3>
<div class=descr>
<ol>
<li>Если <code>ButtonsNumber</code> равен <code>0</code> (флаги <code>FMSG_MB_*</code> не используются) и выведенное сообщение больше не нужно, то плагин <u>должен</u>
восстановить экран, используя функцию <a href="restorescreen.html">RestoreScreen</a> или любым другим путём.
<li>Если <code>ButtonsNumber</code> не равен <code>0</code>, то экран восстанавливает сам Far Manager.
<li>Диалог не выводится, если в качестве <code>Items</code> указан <code>NULL</code> или количество элементов меньше двух.
<li>При указании флагов-кнопок <code>FMSG_MB_*</code> параметр <code>ButtonsNumber</code> игнорируется.
<li>Кнопки могут иметь горячие клавиши.
<li>При использовании флага <code>FMSG_ALLINONE</code> для корректной компиляции кода необходимо произвести явное преобразование типов:
<table border=0><tr>
<td>
<pre class=code>
  Info.Message(&MainGUID,&MsgGUID,
  FMSG_ALLINONE|FMSG_MB_OKCANCEL,
  L"HelpTopic",
  <b>(const wchar_t * const *)</b>L"Title\nItem1\nItem2\nItem3",
  0,0);</pre>
или
<pre class=code>
const wchar_t *Msg=L"Title\nItem1\nItem2\nItem3\nOk\nCancel";
Info.Message(&MainGUID,&MsgGUID,
  FMSG_ALLINONE,
  L"HelpTopic",
  <b>(const wchar_t * const *)</b>Msg,
  0,2);</pre>
</td>
<td><img src="../../images/msg1.gif" width="110" height="96"></td>
</tr></table>
</ol>
</div>

<h3>Пример</h3>
<div class=descr>
Следующая функция выводит на экран диалог-подтверждение на удаление файла:<br>
<img src="../../images/message.gif" width="234" height="63" alt="диалог-подтверждение на удаление файла">
<pre class=code>
BOOL IsDeleted(wchar_t *filename)
{
  const wchar_t *Msg[5];

  Msg[0]=GetMsg(MTitle);       // заголовок сообщения
  Msg[1]=GetMsg(MIsDeleted);   // тело сообщения
  Msg[2]=filename;
  Msg[3]=GetMsg(MDelete);      // последние ButtonsNumber (2) строк - кнопки
  Msg[4]=GetMsg(MCancel);

  return Info.Message(&MainGUID,&MsgGUID,
               0,
               L"DeleteFile",
               Msg,
               sizeof(Msg)/sizeof(Msg[0]),
               2) == 0;
}</pre>

Причём, Info определяется как глобальная переменная:

<pre class=code>struct <a href="../structures/pluginstartupinfo.html">PluginStartupInfo</a> Info;</pre>

...а инициализируется она в функции <a href="../exported_functions/setstartupinfow.html">SetStartupInfoW</a>:

<pre class=code>void WINAPI SetStartupInfoW(struct PluginStartupInfo *Info)
{
  ...
  ::Info=*Info;
  ...
}</pre>

</div>

<div class=see>Смотрите также:</div>
<div class=seecont>
<a href="../service_functions/dialoginit.html">DialogInit</a>
</div>

</body>
</html>
